docs(skill): refresh the grid-api skill for the current API spec by jklein24 · Pull Request #708 · lightsparkdev/grid-api

jklein24 · 2026-07-19T18:13:12Z

Summary

Brings the bundled grid-api Claude skill (.claude/skills/grid-api/) up to date with the current 2025-10-13 spec. The skill drives the API with curl (not the CLI), so this is a spec-freshness pass — audited all four files against openapi/ and fixed the drift.

What was stale / fixed

account-types.md

Removed the bogus paymentRails field from every create body — it's a response-only attribute, not a create input (was in all ~29 curl examples + every "required fields" list).
swiftBic → swiftCode; GBP sortCode 12-34-56 → 123456 (^[0-9]{6}$); XOF countries → region (BJ/CI/SN/TG); UGX/MWK phone patterns → generic; EUR/AED beneficiary required fields (countryOfResidence/address); SGD bankName optional.
Added the INR NEFT/RTGS bank-transfer path, top-level platformAccountId/defaultUmaDepositAccount, 11 missing account types (BDT/CNY/COP/EGP/GHS/GTQ/HTG/JMD/PKR/SLV/SWIFT), and beneficiary optional fields.

SKILL.md / workflows.md

Dropped currency from ACCOUNT destinations (it's UMA-only; ACCOUNT uses paymentRail).
Fixed kyc-link (was GET /customers/kyc-link?query; now POST /customers/{customerId}/kyc-link with a {redirectUri} body).
Removed the invalid PENDING_APPROVAL transaction-status filter; receiver-lookup id → lookupId (+ enumerated supportedCurrencies/requiredPayerDataFields).
Added top-level purposeOfPayment/remittanceInformation, cryptoNetwork for stablecoin realtime funding, transfer-out remittanceInformation/paymentRail, a BUSINESS customer create example (required legalName/taxId/incorporatedOn), and an SCA / PENDING_AUTHORIZATION / authorize subsection.

endpoints.md

Fixed the 2 stale entries (GET /quotes list removed; kyc-link GET→POST), added ~68 missing operations across 12 newer domains (agents, auth, sca, cards, tokens, documents, verifications, discoveries, beneficial-owners, stablecoins, internal-accounts update/export, …), and completed the response-codes table (202/204/403/405/410/423/429).

Auth, base URL, and the discriminated source/destination shapes were already current — unchanged.

Test plan

Documentation-only. Verified every fix against openapi/components/schemas/** and openapi/paths/**; confirmed all curl JSON bodies still parse and no stale tokens remain (paymentRails/swiftBic/countries).

Original PR: #707

The skill drives the API with curl (not the CLI), so this brings its details current with the spec: - account-types.md: remove the bogus paymentRails create field (it's response- only) from all bodies; fix swiftBic->swiftCode, GBP sortCode, XOF countries-> region, UGX/MWK phone patterns, EUR/AED required beneficiary fields, SGD bankName optional; add INR NEFT/RTGS path, platformAccountId/ defaultUmaDepositAccount, 11 missing account types, and beneficiary optionals. - SKILL.md/workflows.md: drop currency from ACCOUNT destinations (UMA-only); fix kyc-link (GET query -> POST /customers/{id}/kyc-link with body); remove invalid PENDING_APPROVAL status filter; receiver id -> lookupId; add top-level purposeOfPayment/remittanceInformation, cryptoNetwork for stablecoin funding, transfer-out remittanceInformation/paymentRail, a BUSINESS customer example, and an SCA/authorize (PENDING_AUTHORIZATION) subsection. - endpoints.md: fix 2 stale entries, add ~68 missing operations across 12 new domains (agents, auth, sca, cards, tokens, documents, verifications, …), and complete the response-codes table.

akanter · 2026-07-19T18:13:29Z

docs(skill): refresh the grid-api skill for the current API spec #708 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

greptile-apps · 2026-07-19T18:17:28Z

Greptile Summary

⚡ 🤘 THE SPEC HAS BEEN REFRESHED, THE STALE SHALL PERISH, ALL HAIL THE CURRENT API 🤘 ⚡
      ___  ____  ____  ____     __   ____  __  
     / __)(  _ \(_  _)(  _ \   /__\ (  _ \(  ) 
    ( (_-. )   / _)(_  )(_) ) /(__)\  )___/ )(__
     \___/(_)\_)(____)(____/ (__)(__)(__) (____)

A large spec-freshness pass over the four files that make up the bundled grid-api Claude skill, bringing it in line with the 2025-10-13 API version. Auth, base URL, and discriminated source/destination shapes were already current and left untouched.

account-types.md removes paymentRails (a response-only field) from all ~20 create curl bodies and required-field lists, fixes swiftBic→swiftCode, GBP sort-code format, XOF countries→region, adds the INR NEFT/RTGS bank-transfer path, and documents 11 new account types (BDT, CNY, COP, EGP, GHS, GTQ, HTG, JMD, PKR, SLV, SWIFT).
endpoints.md adds ~68 missing operations across agents, auth, SCA, cards, tokens, documents, verifications, stablecoins, beneficial-owners, and internal-accounts; fixes the KYC-link endpoint (GET→POST), removes the stale GET /quotes list, and completes the response-codes table.
SKILL.md / workflows.md fix receiver-lookup field names, drop currency from ACCOUNT destinations, add SCA / PENDING_AUTHORIZATION / authorize flow, purposeOfPayment / remittanceInformation, cryptoNetwork for stablecoin funding, and a BUSINESS customer create example — but both files retain stale paymentRails in several create-body examples and tip Update all product names to just Grid #10 still instructs callers to include it.

Confidence Score: 3/5

Safe to merge after fixing the leftover paymentRails references; merging as-is leaves the skill giving contradictory instructions on a core create-account operation.

The bulk of the changes are accurate and well-sourced, but SKILL.md and workflows.md both still embed paymentRails in external-account create bodies (MXN and USD examples) and tip #10 explicitly tells the AI to include it everywhere. These stale fragments directly contradict the PR's stated goal and will cause the skill to generate invalid create requests for MXN and USD accounts until corrected.

.claude/skills/grid-api/SKILL.md (line 223 MXN create example and line 581 tip #10) and .claude/skills/grid-api/references/workflows.md (Workflow 2 MXN example ~line 168 and Workflow 4 USD example ~line 299) — all four still include paymentRails in create bodies.

Important Files Changed

Filename	Overview
.claude/skills/grid-api/SKILL.md	Added BUSINESS customer create, SCA/PENDING_AUTHORIZATION flow, fixed KYC link to POST, removed currency from ACCOUNT destinations, added cryptoNetwork for stablecoin sources — but the MXN example at line 223 and tip #10 at line 581 still include the now-banned paymentRails in create bodies.
.claude/skills/grid-api/references/account-types.md	Comprehensive cleanup: removed paymentRails from all 20+ create curl examples and required-field lists, fixed swiftBic→swiftCode, GBP sortCode format, XOF countries→region, added INR NEFT/RTGS path, 11 new account types, and beneficiary optional fields. All changes appear consistent and complete within this file.
.claude/skills/grid-api/references/workflows.md	Fixed receiver-lookup field names (id→lookupId), removed currency from ACCOUNT destinations in quotes, added SCA note, purposeOfPayment/remittanceInformation, removed PENDING_APPROVAL filter — but Workflow 2 (MXN) and Workflow 4 (USD off-ramp) external-account create examples still include stale paymentRails.
.claude/skills/grid-api/references/endpoints.md	Large addition of ~68 missing operations across agents, auth, SCA, cards, tokens, documents, verifications, beneficial-owners, stablecoins, and internal-accounts; fixed KYC link GET→POST, removed stale GET /quotes list, added response codes 202/204/403/405/410/423/429, and added PENDING_AUTHORIZATION quote status. Appears thorough and internally consistent.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Skill as Claude Skill
    participant API as Grid API

    Note over Skill,API: Standard (non-SCA) quote flow
    Skill->>API: POST /quotes (source, destination, amount)
    API-->>Skill: "200 Quote {status: PENDING}"
    Skill->>API: "POST /quotes/{quoteId}/execute"
    API-->>Skill: "200 Quote {status: PROCESSING}"

    Note over Skill,API: SCA-required regions (EU etc.) — NEW in this PR
    Skill->>API: POST /quotes (source, destination, amount)
    API-->>Skill: "200 or 202 Quote {status: PENDING_AUTHORIZATION, scaChallenge}"
    Skill->>API: "POST /quotes/{quoteId}/authorize {code: "123456"}"
    API-->>Skill: 200 Quote (may still be PENDING_AUTHORIZATION for multi-step)
    Skill->>API: "POST /quotes/{quoteId}/execute"
    API-->>Skill: "200 Quote {status: PROCESSING}"

    Note over Skill,API: KYC link — fixed GET to POST in this PR
    Skill->>API: "POST /customers/{customerId}/kyc-link {redirectUri}"
    API-->>Skill: "200 {kycUrl, token}"

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Skill as Claude Skill
    participant API as Grid API

    Note over Skill,API: Standard (non-SCA) quote flow
    Skill->>API: POST /quotes (source, destination, amount)
    API-->>Skill: "200 Quote {status: PENDING}"
    Skill->>API: "POST /quotes/{quoteId}/execute"
    API-->>Skill: "200 Quote {status: PROCESSING}"

    Note over Skill,API: SCA-required regions (EU etc.) — NEW in this PR
    Skill->>API: POST /quotes (source, destination, amount)
    API-->>Skill: "200 or 202 Quote {status: PENDING_AUTHORIZATION, scaChallenge}"
    Skill->>API: "POST /quotes/{quoteId}/authorize {code: "123456"}"
    API-->>Skill: 200 Quote (may still be PENDING_AUTHORIZATION for multi-step)
    Skill->>API: "POST /quotes/{quoteId}/execute"
    API-->>Skill: "200 Quote {status: PROCESSING}"

    Note over Skill,API: KYC link — fixed GET to POST in this PR
    Skill->>API: "POST /customers/{customerId}/kyc-link {redirectUri}"
    API-->>Skill: "200 {kycUrl, token}"

Comments Outside Diff (2)

.claude/skills/grid-api/SKILL.md, line 223 (link)

Stale paymentRails in create example

The MXN_ACCOUNT curl example in SKILL.md (and its counterpart in workflows.md Workflow 2 at line ~168) still includes "paymentRails": ["SPEI"] inside accountInfo. The whole point of this PR is that paymentRails is a response-only field and must not appear in create bodies — yet both SKILL.md examples (MXN at line 223, and implicitly via tip Update all product names to just Grid #10 which still reads "all fiat accounts require paymentRails" at line ~581) and the two workflow examples for MXN and USD were left with the old field. An AI agent following these examples will send an invalid request body that the API should reject or silently ignore.

Prompt To Fix With AI

This is a comment left during a code review.
Path: .claude/skills/grid-api/SKILL.md
Line: 223

Comment:
**Stale `paymentRails` in create example**

The MXN_ACCOUNT curl example in SKILL.md (and its counterpart in `workflows.md` Workflow 2 at line ~168) still includes `"paymentRails": ["SPEI"]` inside `accountInfo`. The whole point of this PR is that `paymentRails` is a **response-only** field and must not appear in create bodies — yet both SKILL.md examples (MXN at line 223, and implicitly via tip #10 which still reads "all fiat accounts require `paymentRails`" at line ~581) and the two workflow examples for MXN and USD were left with the old field. An AI agent following these examples will send an invalid request body that the API should reject or silently ignore.

How can I resolve this? If you propose a fix, please make it concise.

.claude/skills/grid-api/references/workflows.md, line 168 (link)

Stale paymentRails in Workflow 2 and 4 examples

Both Workflow 2 (MXN_ACCOUNT, line ~168) and Workflow 4 (USD_ACCOUNT off-ramp, line ~299) still include "paymentRails": [...] in the create external account accountInfo body. These are the primary step-by-step guides a user follows when sending an international payment or performing an off-ramp, so stale instructions here will produce invalid requests at exactly the moment a user is trying to run a real payment.

Prompt To Fix With AI

This is a comment left during a code review.
Path: .claude/skills/grid-api/references/workflows.md
Line: 168

Comment:
**Stale `paymentRails` in Workflow 2 and 4 examples**

Both Workflow 2 (MXN_ACCOUNT, line ~168) and Workflow 4 (USD_ACCOUNT off-ramp, line ~299) still include `"paymentRails": [...]` in the create external account `accountInfo` body. These are the primary step-by-step guides a user follows when sending an international payment or performing an off-ramp, so stale instructions here will produce invalid requests at exactly the moment a user is trying to run a real payment.

How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
.claude/skills/grid-api/SKILL.md:223
**Stale `paymentRails` in create example**

The MXN_ACCOUNT curl example in SKILL.md (and its counterpart in `workflows.md` Workflow 2 at line ~168) still includes `"paymentRails": ["SPEI"]` inside `accountInfo`. The whole point of this PR is that `paymentRails` is a **response-only** field and must not appear in create bodies — yet both SKILL.md examples (MXN at line 223, and implicitly via tip #10 which still reads "all fiat accounts require `paymentRails`" at line ~581) and the two workflow examples for MXN and USD were left with the old field. An AI agent following these examples will send an invalid request body that the API should reject or silently ignore.

### Issue 2 of 3
.claude/skills/grid-api/SKILL.md:581
**Tip #10 still says "all fiat accounts require `paymentRails`"**

Tip #10 directly contradicts every change in this PR. The core claim of the diff is that `paymentRails` is a response-only attribute that must **not** be sent on create requests, yet this tip tells the skill (and any AI reading it) the exact opposite. This is the highest-traffic guidance in the file — models weight "Best Practices" bullets heavily — so leaving this stale will systematically generate wrong API calls for every fiat account type.

### Issue 3 of 3
.claude/skills/grid-api/references/workflows.md:168
**Stale `paymentRails` in Workflow 2 and 4 examples**

Both Workflow 2 (MXN_ACCOUNT, line ~168) and Workflow 4 (USD_ACCOUNT off-ramp, line ~299) still include `"paymentRails": [...]` in the create external account `accountInfo` body. These are the primary step-by-step guides a user follows when sending an international payment or performing an off-ramp, so stale instructions here will produce invalid requests at exactly the moment a user is trying to run a real payment.

_{Reviews (1): Last reviewed commit: "docs(skill): refresh grid-api skill for ..." | Re-trigger Greptile}

jklein24 · 2026-07-19T22:51:55Z

@ls-bolt address the greptile comments.

ls-bolt · 2026-07-19T22:52:00Z

📌 Bolt Status

2026-07-19 22:51:59 UTC — ⚡ Agent locked-bulwark-3(#3) started

Feedback

@jklein24

## Summary Follow-up to the skill spec-refresh (#708). That PR removed the response-only `paymentRails` field from the create examples in `account-types.md`, but three references survived elsewhere and contradicted the fix: - `SKILL.md` — `"paymentRails": ["SPEI"]` in the external-account create example - `SKILL.md` — Best Practices tip #10 still asserted *"all fiat accounts require `paymentRails`"* - `references/workflows.md` — `"paymentRails": ["SPEI"]` and `"paymentRails": ["ACH"]` in two create bodies `paymentRails` is not an input on any `*ExternalAccountCreateInfo` schema — Grid selects the rail and returns it on the created account (`common/*AccountInfo.yaml`). Left as-is, the skill instructs callers to send an invalid field on every fiat account create, and tip #10 is high-weight guidance. Tip #10 now points at the field that *is* required (`beneficiary`) and states the rail is server-selected. ## Test plan Docs-only. Verified no `paymentRails` remains in any request body across the skill (the 3 surviving mentions all describe it as response-only), and all 25 curl JSON bodies still parse. Requested by @jklein24 Original PR: #752

ls-bolt Bot mentioned this pull request Jul 19, 2026

docs(skill): refresh the grid-api skill for the current API spec #707

Closed

ls-bolt Bot added the bolt label Jul 19, 2026

jklein24 marked this pull request as ready for review July 19, 2026 18:13

jklein24 requested a review from pengying July 19, 2026 18:13

jklein24 enabled auto-merge (squash) July 19, 2026 18:13

greptile-apps Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread .claude/skills/grid-api/SKILL.md

pengying approved these changes Jul 20, 2026

View reviewed changes

Comment thread .claude/skills/grid-api/SKILL.md

jklein24 merged commit a815d15 into main Jul 20, 2026
16 checks passed

jklein24 deleted the 07-19-grid-skill-spec-refresh branch July 20, 2026 16:27

ls-bolt Bot mentioned this pull request Jul 27, 2026

docs(skill): drop remaining paymentRails from create examples #752

Closed

jklein24 mentioned this pull request Jul 27, 2026

docs(skill): drop remaining paymentRails from create examples #753

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(skill): refresh the grid-api skill for the current API spec - #708

docs(skill): refresh the grid-api skill for the current API spec#708
jklein24 merged 1 commit into
mainfrom
07-19-grid-skill-spec-refresh

jklein24 commented Jul 19, 2026

Uh oh!

akanter commented Jul 19, 2026

Uh oh!

greptile-apps Bot commented Jul 19, 2026 •

edited

Loading

Important Files Changed

Sequence Diagram

Comments Outside Diff (2)

Uh oh!

Uh oh!

jklein24 commented Jul 19, 2026

Uh oh!

ls-bolt Bot commented Jul 19, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jklein24 commented Jul 19, 2026

Summary

What was stale / fixed

Test plan

Uh oh!

akanter commented Jul 19, 2026

Uh oh!

greptile-apps Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Sequence Diagram

Comments Outside Diff (2)

Uh oh!

Uh oh!

jklein24 commented Jul 19, 2026

Uh oh!

ls-bolt Bot commented Jul 19, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

greptile-apps Bot commented Jul 19, 2026 •

edited

Loading